home *** CD-ROM | disk | FTP | other *** search
/ Informática Multimedia 1995 April / Informatica Multimedia CD - Epimundo.iso / DOS / FILEFIND / CHANGE / CHANGE.TXT < prev    next >
Encoding:
Text File  |  1993-02-07  |  25.9 KB  |  620 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                                        CHANGE
  9.  
  10.                                      User Manual
  11.  
  12.                                     Version 2.05
  13.  
  14.  
  15.  
  16.  
  17.                                    John W. Clinton
  18.                                     P.O. Box 678
  19.                                    Boston, MA 02136
  20.                                     Bix: JClinton
  21.                                    CIS: 70244,1340
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.             Program and accompanying documentation copyright 1989-'92 by
  61.                                   John W. Clinton.
  62.                                 All rights reserved.
  63.  
  64.  
  65.  
  66.  
  67.                                     CHANGE v2.05
  68.                                     CHANGE v2.05
  69.                                     CHANGE v2.05
  70.  
  71.             ____________
  72.             Introduction
  73.             ____________
  74.             Introduction
  75.             ____________
  76.             Introduction
  77.  
  78.  
  79.             Please pass this software around to your friends and
  80.             associates. Feel free to use this software for a month. If
  81.             you find CHANGE as useful as I do, please Register!. Full
  82.             registration is only $25.00 in U.S. funds.
  83.  
  84.             Registered  Users  receive  the  latest   advertisement-free
  85.             version of the software. Delivery options include EMail  via
  86.             Bix, Compuserve, or  U.S. mail. Registered  Users will  also
  87.             receive all updates made  to CHANGE for a  period of 1  year
  88.             from the date of registration.  Updates to CHANGE have  been
  89.             averaging one every six to eight months. Registered versions
  90.             of the software are smaller and run faster. They do not have
  91.             any of the advertising or other annoying banners. All of the
  92.             output may be redirected using DOS redirection operators  or
  93.             may be suppressed  completely. I often  include a number  of
  94.             other useful utilities with the distribution media as  space
  95.             and availability permit. Any  special modifications you  may
  96.             require  are  available  to  registered  users  by   special
  97.             arrangement. As a matter of policy  I do not currently  make
  98.             the source for any products available.
  99.  
  100.                          Help support the Shareware Concept!
  101.                          Help support the Shareware Concept!
  102.                          Help support the Shareware Concept!
  103.  
  104.             ___________
  105.             Disclaimer:
  106.             ___________
  107.             Disclaimer:
  108.             ___________
  109.             Disclaimer:
  110.  
  111.  
  112.             This software is provided 'as is' and is without any
  113.             warranty of any kind, whether express or implied, including,
  114.             but not limited to the implied warranties of fitness for a
  115.             particular purpose. I will not be liable for any special,
  116.             indirect, incidental, consequential or similar damages due
  117.             to any loss of any kind related to the use of this software
  118.             or for any other reason, even if I or an agent of mine has
  119.             been advised of the possibility of such damages. In no event
  120.             shall my liability for any damages ever exceed the price
  121.             paid for the license to use software, regardless of the form
  122.             of the claim. The person choosing to use the software
  123.             assumes any and all risks as to the quality and performance
  124.             of the software.
  125.  
  126.             ________________
  127.             Acknowledgments:
  128.             ________________
  129.             Acknowledgments:
  130.             ________________
  131.             Acknowledgments:
  132.  
  133.  
  134.             Special thanks to my wife Loretta for putting up with all of
  135.                      the time I put in on these little projects.
  136.              Special thanks to Roedy Green for his constructive feedback
  137.                           on the program and documentation.
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.                                           2
  145.  
  146.  
  147.  
  148.  
  149.                                     CHANGE v2.05
  150.                                     CHANGE v2.05
  151.                                     CHANGE v2.05
  152.  
  153.             ____________
  154.             Description:
  155.             ____________
  156.             Description:
  157.             ____________
  158.             Description:
  159.  
  160.  
  161.             CHANGE allows you to make global changes to the contents of
  162.             files. It works in much the same way as your favorite word
  163.             processor's global change feature.
  164.  
  165.             There are two major differences.
  166.  
  167.                The change(s) are propagated through all of the files in
  168.                a set of comma delimited wildcard filespecs on the
  169.                command line. This can include all files in all sub
  170.                directories of the current sub directory or every
  171.                directory on all disks attached to the system.
  172.  
  173.                You may specify all of the changes to be made with one
  174.                pass through the file(s).
  175.  
  176.             This utility is indispensable when:
  177.             This utility is indispensable when:
  178.             This utility is indispensable when:
  179.  
  180.                Working with a large number of source files and you need
  181.                to change variable or function names, literals, etc.
  182.                globally.
  183.  
  184.                Working on old code and you want to retrofit it with new
  185.                naming standards to bring the code up to date.
  186.  
  187.                Anytime there are a large number of files and a large
  188.                number of changes that need to be made _______
  189.                                                       quickly.
  190.  
  191.  
  192.             Usage:
  193.             Usage:
  194.             Usage:
  195.  
  196.             If no parameters are passed in to CHANGE a usage summary
  197.             will be printed. Additional help is available by using the
  198.             /HELP switch.
  199.  
  200.             In general:
  201.             In general:
  202.             In general:
  203.  
  204.                  CHANGE <filespeclist> <matchString> <replacementString>
  205.             [...] [/switches]
  206.  
  207.             CHANGE - locates all occurrences of the specified file(s)
  208.             and replaces the search string(s) with the specified
  209.             replacement string(s).
  210.  
  211.             Each filespec in the <filespeclist> may contain a drive,
  212.             path and filename. The drive is the volume that will be
  213.             searched. All files matching the files in the <filespeclist>
  214.             will be search and modified as needed.
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.                                           3
  222.  
  223.  
  224.  
  225.  
  226.                                     CHANGE v2.05
  227.                                     CHANGE v2.05
  228.                                     CHANGE v2.05
  229.  
  230.             Examples:
  231.             Examples:
  232.             Examples:
  233.  
  234.              Change all C sources in the current directory. Make 'aa'
  235.             into 'bb'.
  236.  
  237.                  CHANGE *.c 'aa' 'bb'
  238.  
  239.             Change all C source files in .\SRC, all Headers in .\INC and
  240.             all files in .\TMP.  Make 'foo' into 'foobar'.
  241.  
  242.                  CHANGE SRC\*.C,INC\*.H,TMP\*.* 'foo','foobar'
  243.  
  244.             Search and Replace strings are single words or quoted
  245.             strings. Either single or double quotes will do. Everything
  246.             on the command line is uppercased unless surrounded by
  247.             quotes. The Search and Replace parameters may be separated
  248.             by spaces or commas. If DOS redirection characters are part
  249.             of any string on the command line they MUST be surrounded by
  250.             DOUBLE QUOTES!  That is the ONLY way to prevent DOS from
  251.             usurping them.
  252.  
  253.             __________________
  254.             Customizing CHANGE
  255.             __________________
  256.             Customizing CHANGE
  257.             __________________
  258.             Customizing CHANGE
  259.  
  260.  
  261.             CHANGE is now being shipped with a utility called CHGINST.
  262.             This program allows you to re configure the defaults of the
  263.             most commonly used (but not all) switches to suit your own
  264.             specific needs. To use CHGINST just run it from the command
  265.             line. It will search for CHANGE in the current directory and
  266.             along the DOS PATH. If change cannot be found it will stop
  267.             and suggest the following:
  268.  
  269.             Either move CHANGE into the same directory with CHGINST,
  270.             move CHANGE into a directory along your DOS PATH, or invoke
  271.             CHGINST with the name of the directory that CHANGE is in as
  272.             a parameter.
  273.  
  274.             Example:
  275.             Example:
  276.             Example:
  277.  
  278.                  CHANGE is in C:\UTILS and CHGINST is in C:\ use
  279.  
  280.                  CHGINST        -> if C:\UTILS is in your PATH,
  281.  
  282.                  CHGINST C:\UTILS  -> if C:\UTILS is NOT in your PATH.
  283.  
  284.                Note:
  285.                Note:
  286.                Note:
  287.  
  288.                  CHGINST DOES depend on CHANGE being called CHANGE.EXE!
  289.  
  290.             ______________________________
  291.             General command line handling:
  292.             ______________________________
  293.             General command line handling:
  294.             ______________________________
  295.             General command line handling:
  296.  
  297.  
  298.             Switches are placed anywhere on the command line except
  299.             within quoted strings.  Switches may be abbreviated to the
  300.  
  301.  
  302.                                           4
  303.  
  304.  
  305.  
  306.  
  307.                                     CHANGE v2.05
  308.                                     CHANGE v2.05
  309.                                     CHANGE v2.05
  310.  
  311.             smallest unique string among the switches the program
  312.             supports. The absolute minimum number of characters required
  313.             for each of the switches is indicated by the uppercase part
  314.             of the switch names on the help screen. Everything on the
  315.             command line is converted to uppercase unless surrounded by
  316.             quotes.  Both double (") and single (') quotes are
  317.             supported. If you need imbedded special characters or spaces
  318.             in a parameter surround it with quotes. Text containing
  319.             single quotes may be surrounded by double quotes, and text
  320.             containing single quotes may be surrounded by double quotes.
  321.             Non printable characters may be placed into the quoted
  322.             strings on the command line or in indirect files (discussed
  323.             below) using the following syntax: #nnn or ^a where 'nnn' is
  324.             the Decimal ASCII code for the desired character and 'a' is
  325.             '@'..'Z' corresponding to ^@ through ^Z.
  326.  
  327.             DOS Notes:
  328.             DOS Notes:
  329.             DOS Notes:
  330.  
  331.                1.DOS has a gotcha for strings like "Contains 4 spaces '
  332.                  '". It will convert the 4 spaces to a single space
  333.                  before CHANGE gets control. This is only a problem for
  334.                  parameters entered on the command line. Indirect files
  335.                  handle this situation correctly. CHANGE also supports
  336.                  an enviroment string 'CMDLINE=' if it is present as a
  337.                  source for it's command line. This permits 4DOS users
  338.                  to automatically avoid this problem. It also allows
  339.                  them to support up to 255 characters on the command
  340.                  line.
  341.  
  342.                2.If your string(s) contain the DOS re-direction
  343.                  operators '<' '>' or '|' then you MUST enclose the
  344.                  string in DOUBLE QUOTES! Double Quotes will prevent DOS
  345.                  from using them for redirection of the standard
  346.                  input/output files.
  347.  
  348.             Examples:
  349.             Examples:
  350.             Examples:
  351.  
  352.                  #007  - Is the ASCII BEL Character.
  353.  
  354.                  ^G   - also the ASCII BEL character.
  355.  
  356.                  5#0075 - would be converted to 5's surrounding a BEL.
  357.  
  358.                  x#7x  - would be converted to x's surrounding a BEL.
  359.  
  360.             The leading zeros are required in ex. 1&3 to keep the other
  361.             numbers from confusing CHANGE. They may be omitted when
  362.             there is only one way to interpret the data. These special
  363.             characters ( '#' and '^' ) may appear in your data as long
  364.             as they are unambiguous. When in doubt, use two of the
  365.             special characters to get one. See the examples below.
  366.  
  367.             Normally the DOS command line supports parameters up to 128
  368.             bytes. Indirect parameter files may be used for changes that
  369.  
  370.  
  371.                                           5
  372.  
  373.  
  374.  
  375.  
  376.                                     CHANGE v2.05
  377.                                     CHANGE v2.05
  378.                                     CHANGE v2.05
  379.  
  380.             either require more than 128 bytes of input OR for CHANGEs
  381.             that may be used again in the future. The total size of the
  382.             parameters may now total in excess of 64KB.
  383.  
  384.             _________________________
  385.             Indirect Parameter Files:
  386.             _________________________
  387.             Indirect Parameter Files:
  388.             _________________________
  389.             Indirect Parameter Files:
  390.  
  391.  
  392.             To use an indirect file place an '@' at the beginning of the
  393.             name of the indirect file on the command line. The indirect
  394.             file itself may contain anything that is normally allowed on
  395.             the command line for CHANGE.
  396.  
  397.               Switches specified in the indirect file may be overridden
  398.             or added to by specifying the new switches on the command
  399.             line following the indirect file's name.
  400.  
  401.                  CHANGE TEST.PAS @varchang.lis /SUBDIR
  402.  
  403.             This would include the list of change strings found in the
  404.             file VARCHANG.LIS (in the current directory).  The lines in
  405.             the file are concatenated together with a space appended to
  406.             the end of each line. If the resulting command line has an
  407.             odd number of CHANGE strings specified an error will be
  408.             reported.
  409.  
  410.                A reminder about Case:
  411.                A reminder about Case:
  412.                A reminder about Case:
  413.  
  414.             Remember that the command line is always uppercased first.
  415.             If you are using the /CASE switch then you will probably
  416.             want to surround your match and replace strings with quotes.
  417.             If you want lower case in your replacements then be sure to
  418.             surround the replace string with quotes! Be sure when using
  419.             foreign language character sets or plain binary data that
  420.             you use both quoting and the /CASE switch to prevent any
  421.             potential problems with the interpretation of these
  422.             characters!
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.                                           6
  444.  
  445.  
  446.  
  447.  
  448.                                     CHANGE v2.05
  449.                                     CHANGE v2.05
  450.                                     CHANGE v2.05
  451.  
  452.             More Examples:
  453.             More Examples:
  454.             More Examples:
  455.  
  456.             1. To rename the ever popular 'foobar' variable to 'MyVar'
  457.               in the program 'test.pas' you would use the following
  458.               CHANGE command:
  459.  
  460.                  CHANGE test.pas 'foobar' 'MyVar'
  461.  
  462.             2. To change foobar to @#^foobar (use of special chars)
  463.               double up the special chars. Use:
  464.  
  465.                  CHANGE *.pas 'foobar' '@@##^^foobar'
  466.  
  467.             3. To change strings that contain special characters you
  468.               need to represent the special characters in some fashion
  469.               and 'allow' CHANGE to see them. Any character in the ASCII
  470.               set may be specified in a QUOTED STRING by using a #
  471.               followed by the character's three digit decimal ASCII
  472.               code, for instance #007 is the BEL character.
  473.  
  474.             To reformat a LF delimited text file into a more standard
  475.             CRLF delimited file use the following:
  476.  
  477.                  CHANGE STRANGE.C ^J ^M^J
  478.  
  479.             4. Several CHANGEs may be combined. The following CHANGE
  480.               turns the variables called 'var1' into 'MyOtherVar' and
  481.               reformats a LF delimited text file to a CRLF delimited
  482.               text file.
  483.  
  484.                  CHANGE *.PAS 'foobar','MyVar' 'var1','MyOtherVar'
  485.             #10,#13#10
  486.  
  487.             5. If you have a large or complex change like the one above
  488.               it is often better to use an indirect file. The indirect
  489.               file, 'BIGCHG.IND', for that change would look like this:
  490.                  !===Start of file BIGCHG.IND===
  491.                  ! Comments are allowed within indirect files.
  492.                  ! They are lines that being with an '!'
  493.                  'foobar', 'MyVar'
  494.                  'var1',        'MyOtherVar'
  495.                  #10,      #13#10
  496.                  !===End of file BIGCHG.IND===
  497.  
  498.             And the invocation of CHANGE would be:
  499.  
  500.                  CHANGE *.PAS @BIGCHG.IND
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.                                           7
  511.  
  512.  
  513.  
  514.  
  515.                                     CHANGE v2.05
  516.                                     CHANGE v2.05
  517.                                     CHANGE v2.05
  518.  
  519.             ______________
  520.             Change History
  521.             ______________
  522.             Change History
  523.             ______________
  524.             Change History
  525.  
  526.  
  527.             A complete history of CHANGE has been moved to the file
  528.             HISTORY.DOC.
  529.  
  530.             _______________
  531.             Known Problems:
  532.             _______________
  533.             Known Problems:
  534.             _______________
  535.             Known Problems:
  536.  
  537.  
  538.             The following problems are known to exist in this version:
  539.  
  540.             1. When CHANGE is used on a file that had DOS file
  541.               protection bits set, the protection bits are LOST! When
  542.               CHANGE finds one of these files and it is told it is Ok to
  543.               change it, CHANGE sets the file's protection to ARCHIVE
  544.               only. When the original file is renamed to the .BAK
  545.               version it is left with just the ARCHIVE bit set.  The new
  546.               version of the file is set to ARCHIVE only. It is left up
  547.               to the User to reset the file protection appropriately.
  548.  
  549.             I don't view this as a bug, but you should be aware of it.
  550.  
  551.             2. When running CHANGE on a Netware file volume you must
  552.               have the privileges required to edit the files and to
  553.               create a subdirectory in the directory containing the
  554.               file(s) to be CHANGEd.
  555.  
  556.             ________________
  557.             Planned Changes:
  558.             ________________
  559.             Planned Changes:
  560.             ________________
  561.             Planned Changes:
  562.  
  563.  
  564.             CHANGE is currently 92% Turbo Pascal v6.0, the remainder is
  565.             TASM.
  566.  
  567.             If I get enough requests I will be adding unix grep style
  568.             'regular expression' pattern matching. If you need this
  569.             please let me know! ( So far there has been 1 inquiry )
  570.  
  571.             ______________________
  572.             Encountering Problems:
  573.             ______________________
  574.             Encountering Problems:
  575.             ______________________
  576.             Encountering Problems:
  577.  
  578.  
  579.             If you wish to report a problem with this software I can be
  580.             reached at the above address, or send electronic mail to me
  581.             via Bix (JClinton) or CompuServe (70244,1340). Please
  582.             provide as much detail into the nature of the problem
  583.             encountered, along with the system configuration details and
  584.             SMALL examples of the data that demonstrates the problem.
  585.  
  586.               As always I welcome new ideas, comments and suggestions!
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.                                           8
  596.  
  597.  
  598.  
  599.  
  600.                                     CHANGE v2.05
  601.                                     CHANGE v2.05
  602.                                     CHANGE v2.05
  603.  
  604.             Appendix A
  605.             Appendix A
  606.             Appendix A
  607.  
  608.             Currently supported switches:
  609.             Currently supported switches:
  610.             Currently supported switches:
  611.                           (Only the upper case characters are required.)
  612.  
  613.             /Help           - Displays this message.
  614.             /[NO]ALL        - Causes all fixed drives to be completely
  615.                             searched.
  616.             /[NO]SHow_context   - Causes the line that matched to be
  617.                             displayed prior to the change and prompts
  618.                             the user to confirm that specific change.
  619.                             Changes may be allowed (Press 'Y');
  620.                             Disallowed (press 'N' or RETURN); Make all
  621.                             of the changes found from here to the end
  622.                             of this file, (press ^Z); Make no more
  623.                             changes to this file, but keep the changes
  624.                             made so far (press ESC); or abort the
  625.                             changes made to this file completely,
  626.                             (press '^C'). Press ? for additional help
  627.                             at the CHANGE prompt. The default is
  628.                             /SHow_context in CHANGE as shipped, See the
  629.                             notes on the CHGINST program below.
  630.              /[NO]HEX_display   - When /SHow_context is in use this
  631.                             makes the HexViewer provide the first look
  632.                             at the file. 'A' and 'H' can still be used
  633.                             to switch between the Hex and ASCII
  634.                             viewers.
  635.              /[NO]Prefix_change - Only make the CHANGE if the
  636.                             matchstring is at the beginning of a
  637.                             string. Match 'thisx', not 'xthisx' or
  638.                             'xthis'.
  639.              /[NO]SUffix_change  - Only make the CHANGE if the
  640.                             matchstring is at the end of a string.
  641.                             Match 'xthis', not 'xthisx' or 'thisx'.
  642.              /[NO]Whole_words   - Only make a CHANGE if the matchstring
  643.                             is a whole surrounded by non alphanumerics.
  644.                             Match 'this', not 'xthis' or 'thisx'.
  645.              /[NO]Sub directories    - Causes all sub directories of the
  646.                             current one to be searched. The default is
  647.                             \NOSUbdirectories in CHANGE as shipped, See
  648.                             the notes on the CHGINST program below.
  649.              /[NO]Case_sensitive     - Allows the searching to be
  650.                             performed respecting the case of the match
  651.                             and replacement strings. The default is
  652.                             /NOCASE_SENSITIVE in CHANGE as shipped, See
  653.                             the notes on the CHGINST program below.
  654.              /[NO]Unique_bak    - Guarantees that backup files created
  655.                             will be unique. This will prevent CHANGE
  656.                             from deleting a backup file that already
  657.                             exists. CHANGE automatically enables this
  658.                             option when wildcard filespecs (like
  659.                             TEST.*) are specified that can overwrite
  660.                             backup files that CHANGE just created.
  661.  
  662.  
  663.  
  664.                                           9
  665.  
  666.  
  667.  
  668.  
  669.                                     CHANGE v2.05
  670.                                     CHANGE v2.05
  671.                                     CHANGE v2.05
  672.  
  673.              The default is /Unique_bak in CHANGE as shipped, See the
  674.                             notes on the CHGINST program below.
  675.              /[NO]Floppysize=n  - Defines the size in KB of the largest
  676.                             floppy on your system you want searched. By
  677.                             default drives a: and B: are not checked at
  678.                             all. EX: /ALL/FLOPPYSIZE=1200 would check
  679.                             the size of each drive before searching.
  680.                             Only those 1.2MB and up would be searched.
  681.              /[NO]COnfirm_change     - Prompts for permission to make
  682.                             changes to each FILESPEC matched that
  683.                             actually contains a match. This allows the
  684.                             user to selectively modify files.
  685.              /ANy_attribute - Change all files matching the FILESPEC,
  686.                             regardless of special file attributes.
  687.                             /CONFIRM_CHANGE option is set by default,
  688.                             but may be overridden.
  689.              /[NO]Log       - Do [NOT] write progress messages to the
  690.                             console. The default is /NOLog in CHANGE as
  691.                             shipped, See the notes on the CHGINST
  692.                             program below.
  693.              /[NO]BACKups   - Do [NOT] rename the original files to
  694.                             .BAK. The default is /BACKups in CHANGE as
  695.                             shipped, See the notes on the CHGINST
  696.                             program below.
  697.             * /[NO]Quote_mode=? - Do [NOT] use the quote 'respect'
  698.                             features.
  699.                             ?: Only_in_quotes  == Just change things
  700.                             WITHIN quotes.
  701.                             Protect_quotes     == Just change things
  702.                             OUTSIDE quotes.
  703.                             Ignore_quotes == (delivered default) change
  704.                             in and out of quotes.
  705.                             The default is /Quote_mode=Ignore
  706.             * /QUote_char=? - Specify a quote character.
  707.                             ?: Single_quotes   == Specify that quotes
  708.                             are "'".
  709.                             Double_quotes == Specify that quotes are
  710.                             '"'.
  711.                             <any_char>    == Specify a custom quote
  712.                             character.
  713.                             This character may be (paradoxically)
  714.                             presented in quotes!
  715.                             The default is /QUOTE_CHAR='
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.                                          10
  730.